<!doctype html>
<html lang="en" class="page-type-section">
<head prefix="og: http://ogp.me/ns#">
<meta charset="utf-8">
<title>macro, nested, return - FreeMarker 手册</title>
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width,initial-scale=1">
<meta name="format-detection" content="telephone=no">
<meta property="og:site_name" content="FreeMarker 手册">
<meta property="og:title" content="macro, nested, return">
<meta property="og:locale" content="en_US">
<meta property="og:url" content="http://freemarker.org/docs/ref_directive_macro.html">
<link rel="canoical" href="http://freemarker.org/docs/ref_directive_macro.html">
<link rel="icon" href="favicon.png" type="image/png">
<link rel="stylesheet" type="text/css" href="docgen-resources/docgen.min.css">
</head>
<body itemscope itemtype="https://schema.org/Code">
    <meta itemprop="url" content="http://freemarker.org/docs/">
    <meta itemprop="name" content="FreeMarker 手册">

  <!--[if lte IE 9]>
  <div style="background-color: #C00; color: #fff; padding: 12px 24px;">Please use a modern browser to view this website.</div>
  <![endif]--><div class="header-top-bg"><div class="site-width header-top"><a class="logo" href="http://freemarker.org" role="banner">            <img itemprop="image" src="logo.png" alt="FreeMarker">
</a><ul class="tabs"><li><a href="http://freemarker.org/">Home</a></li><li class="current"><a href="index.html">Manual</a></li><li><a class="external" href="http://freemarker.org/docs/api/index.html">Java API</a></li></ul><ul class="secondary-tabs"><li><a class="tab icon-heart" href="http://freemarker.org/contribute.html" title="Contribute"><span>Contribute</span></a></li><li><a class="tab icon-bug" href="https://sourceforge.net/p/freemarker/bugs/new/" title="Report a Bug"><span>Report a Bug</span></a></li><li><a class="tab icon-download" href="http://freemarker.org/freemarkerdownload.html" title="Download"><span>Download</span></a></li></ul></div></div><div class="header-bottom-bg"><div class="site-width search-row"><a href="toc.html" class="navigation-header">Manual</a><div class="navigation-header"></div></div><div class="site-width breadcrumb-row"><ul class="breadcrumb" itemscope itemtype="http://schema.org/BreadcrumbList"><li class="step-0" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="toc.html"><span itemprop="name">FreeMarker 手册</span></a></li><li class="step-1" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref.html"><span itemprop="name">模板语言参考 </span></a></li><li class="step-2" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directives.html"><span itemprop="name">指令参考</span></a></li><li class="step-3" itemprop="itemListElement" itemscope itemtype="http://schema.org/ListItem"><a class="label" itemprop="item" href="ref_directive_macro.html"><span itemprop="name">macro, nested, return</span></a></li></ul><div class="bookmarks" title="Bookmarks"><span class="sr-only">Bookmarks:</span><ul class="bookmark-list"><li><a href="alphaidx.html">Alpha. index</a></li><li><a href="gloss.html">Glossary</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions</a></li><li><a href="ref_builtins_alphaidx.html">?builtins</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_specvar.html">.spec_vars</a></li><li><a href="app_faq.html">FAQ</a></li></ul></div></div></div>    <div class="main-content site-width">
      <div class="content-wrapper">
  <div id="table-of-contents-wrapper" class="col-left">
      <script>var breadcrumb = ["FreeMarker 手册","模板语言参考 ","指令参考","macro, nested, return"];</script>
      <script src="toc.js"></script>
      <script src="docgen-resources/main.min.js"></script>
  </div>
<div class="col-right"><div class="page-content"><div class="page-title"><div class="pagers top"><a class="paging-arrow previous" href="ref_directive_local.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_noparse.html"><span>Next</span></a></div><div class="title-wrapper">
<h1 class="content-header header-section1" id="ref_directive_macro" itemprop="headline">macro, nested, return</h1>
</div></div><div class="page-menu">
<div class="page-menu-title">Page Contents</div>
<ul><li><a class="page-menu-link" href="#autoid_103" data-menu-target="autoid_103">概要</a></li><li><a class="page-menu-link" href="#autoid_104" data-menu-target="autoid_104">描述</a><ul><li><a class="page-menu-link" href="#autoid_105" data-menu-target="autoid_105">nested</a></li><li><a class="page-menu-link" href="#autoid_106" data-menu-target="autoid_106">return</a></li></ul></li></ul> </div><a name="ref.directive.macro"></a>
          



<h2 class="content-header header-section2" id="autoid_103">概要</h2>


          
<pre class="metaTemplate">
<code class="inline-code">&lt;#macro <em class="code-color">name</em> <em class="code-color">param1</em> <em class="code-color">param2</em> <em class="code-color">... paramN</em>&gt;
  <em class="code-color">...</em>
  &lt;#nested <em class="code-color">loopvar1</em>, <em class="code-color">loopvar2</em>, <em class="code-color">...</em>, <em class="code-color">loopvarN</em>&gt;
  <em class="code-color">...</em>
  &lt;#return&gt;
  <em class="code-color">...</em>
&lt;/#macro&gt;</code>
</pre>


          <p>这里：</p>

          <ul>
            <li>
              <code class="inline-code"><em class="code-color">name</em></code>：
			  宏变量的名称，它不是表达式。和 <a href="dgui_template_exp.html#dgui_template_exp_var_toplevel">顶层变量</a> 
			  的语法相同，比如 <code class="inline-code">myMacro</code> 或 <code class="inline-code">my\-macro</code>。
			  然而，它可以被写成字符串的形式，如果宏名称中包含保留字符时，这是很有用的，
			  比如 <code class="inline-code">&lt;#macro &quot;foo~bar&quot;&gt;<em class="code-color">...</em></code>。
			  注意这个字符串没有扩展插值(如 <code class="inline-code">&quot;${foo}&quot;</code>)。
            </li>

            <li>
              <code class="inline-code"><em class="code-color">param1</em></code>，
              <code class="inline-code"><em class="code-color">param2</em></code>，等...：
			  <a href="dgui_misc_var.html">局部变量</a> 的名称，存储参数的值
			  (不是表达式)，在 <code class="inline-code">=</code> 号后面和默认值(是表达式)是可选的。
			  默认值也可以是另外一个参数，比如 <code class="inline-code">&lt;#macro section title
              label=title&gt;</code>。参数名称和 <a href="dgui_template_exp.html#dgui_template_exp_var_toplevel">顶层变量</a> 
			  的语法相同，所以有相同的特性和限制。
            </li>

            <li>
              <code class="inline-code"><em class="code-color">paramN</em></code>，
				最后一个参数，可能会有三个点(<code class="inline-code">...</code>)，
				这就意味着宏接受可变数量的参数，不匹配其它参数的参数可以作为最后一个参数
				(也被称作笼统参数)。当宏被命名参数调用，
				<code class="inline-code"><em class="code-color">paramN</em></code> 
				将会是包含宏的所有未声明的键/值对的哈希表。当宏被位置参数调用，
				<code class="inline-code"><em class="code-color">paramN</em></code> 将是额外参数的序列。
				(在宏内部，要查找参数，可以使用 
				<code class="inline-code"><em class="code-color">myCatchAllParam</em>?is_sequence</code>。)
            </li>

            <li>
              <code class="inline-code"><em class="code-color">loopvar1</em></code>，
              <code class="inline-code"><em class="code-color">loopvar2</em></code>等...：
			  可选的，<a href="dgui_misc_var.html">循环变量</a> 的值，
			  是 <code class="inline-code">nested</code> 指令想为嵌套内容创建的。这些都是表达式。
            </li>
          </ul>

          <p><code class="inline-code">return</code> 和 <code class="inline-code">nested</code>
		  指令是可选的，而且可以在 <code class="inline-code">&lt;#macro
          <em class="code-color">...</em>&gt;</code> 和 
		  <code class="inline-code">&lt;/#macro&gt;</code> 之间被用在任意位置和任意次数。</p>

          <p>没有默认值的参数必须在有默认值参数
          (<code class="inline-code"><em class="code-color">paramName</em>=<em class="code-color">defaultValue</em></code>)
		  之前。</p>
        
          



<h2 class="content-header header-section2" id="autoid_104">描述</h2>


          <p>创建一个宏变量(在当前命名空间中，如果你知道命名空间的特性)。
		  如果你对宏和自定义指令不了解，你应该阅读 <a href="dgui_misc_userdefdir.html">自定义指令指南</a>。</p>

          <p>宏变量存储模板片段(称为宏定义体)可以被用作 <a href="ref_directive_userDefined.html#ref.directive.userDefined">自定义指令</a>。
		  这个变量也存储自定义指令的被允许的参数名。当你将这个变量作为指令时，
		  你必须给所有参数赋值，除了有默认值的参数。
		  默认值当且仅当你调用宏而不给参数赋值时起作用。</p>

          <p>变量会在模板开始时被创建；而不管 <code class="inline-code">macro</code> 
		  指令放置在模板的什么位置。因此，这样也可以：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#-- call the macro; the macro variable is already created: --&gt;
&lt;@test/&gt;
...

&lt;#-- create the macro variable: --&gt;
&lt;#macro test&gt;
  Test text
&lt;/#macro&gt;</pre></div>

          <p>然而，如果宏定义被插在 <code class="inline-code">include</code> 指令中，
		  它们直到 FreeMarker 执行 <code class="inline-code">include</code> 指令时才会可用。</p>

          <p>例如：没有参数的宏：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro test&gt;
  Test text
&lt;/#macro&gt;
&lt;#-- call the macro: --&gt;
&lt;@test/&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  Test text
 </pre></div>

          <p>示例：有参数的宏：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro test foo bar baaz&gt;
  Test text, and the params: ${foo}, ${bar}, ${baaz}
&lt;/#macro&gt;
&lt;#-- call the macro: --&gt;
&lt;@test foo=&quot;a&quot; bar=&quot;b&quot; baaz=5*5-2/&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  Test text, and the params: a, b, 23
   </pre></div>

          <p>示例：有参数和默认值参数的宏：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro test foo bar=&quot;Bar&quot; baaz=-1&gt;
  Test text, and the params: ${foo}, ${bar}, ${baaz}
&lt;/#macro&gt;
&lt;@test foo=&quot;a&quot; bar=&quot;b&quot; baaz=5*5-2/&gt;
&lt;@test foo=&quot;a&quot; bar=&quot;b&quot;/&gt;
&lt;@test foo=&quot;a&quot; baaz=5*5-2/&gt;
&lt;@test foo=&quot;a&quot;/&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  Test text, and the params: a, b, 23
  Test text, and the params: a, b, -1
  Test text, and the params: a, Bar, 23
  Test text, and the params: a, Bar, -1
 </pre></div>

          <p>示例：更为复杂的宏。</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro list title items&gt;
  &lt;p&gt;${title?cap_first}:
  &lt;ul&gt;
    &lt;#list items as x&gt;
      &lt;li&gt;${x?cap_first}
    &lt;/#list&gt;
  &lt;/ul&gt;
&lt;/#macro&gt;
&lt;@list items=[&quot;mouse&quot;, &quot;elephant&quot;, &quot;python&quot;] title=&quot;Animals&quot;/&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  &lt;p&gt;Animals:
  &lt;ul&gt;
      &lt;li&gt;Mouse
      &lt;li&gt;Elephant
      &lt;li&gt;Python
  &lt;/ul&gt;
 </pre></div>

          <p>示例：支持多个参数和命名参数的宏：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro img src extra...&gt;
  &lt;img src=&quot;/context${src?html}&quot; 
  &lt;#list extra?keys as attr&gt;
    ${attr}=&quot;${extra[attr]?html}&quot;
  &lt;/#list&gt;
  &gt;
&lt;/#macro&gt;
&lt;@img src=&quot;/images/test.png&quot; width=100 height=50 alt=&quot;Test&quot;/&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  &lt;img src=&quot;/context/images/test.png&quot;
    alt=&quot;Test&quot;
    height=&quot;50&quot;
    width=&quot;100&quot;
  &gt;</pre></div>

          <p>示例：支持多个位置参数的宏，不管是否使用命名或位置参数传递：</p>

          

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro m a b ext...&gt;
  a = ${a}
  b = ${b}
  &lt;#if ext?is_sequence&gt;
    &lt;#list ext as e&gt;
      ${e?index} = ${e}
    &lt;/#list&gt;
  &lt;#else&gt;
    &lt;#list ext?keys as k&gt;
      ${k} = ${ext[k]}
    &lt;/#list&gt;
  &lt;/#if&gt;
&lt;/#macro&gt;

&lt;@m 1 2 3 4 5 /&gt;

&lt;@m a=1 b=2 c=3 d=4 e=5 data\-foo=6 myns\:bar=7 /&gt;</pre></div>

          <p>将会输出：</p>

          

<div class="code-wrapper"><pre class="code-block code-output">  a = 1
  b = 2
      0 = 3
      1 = 4
      2 = 5

  a = 1
  b = 2
      c = 3
      d = 4
      e = 5
      data-foo=6
      myns:bar=7</pre></div>

            <div class="callout warning">
    <strong class="callout-label">Warning!</strong>

            <p>当前，命名的笼统参数是无序的，也就是说，不知道它们枚举时的顺序。
			那么它们不会按相同传递顺序返回(上述示例输出相同的顺序只是为了理解)。</p>
            </div>


          
            



<h3 class="content-header header-section3" id="autoid_105">nested</h3>


            <a name="ref.directive.nested"></a>

            <p><code class="inline-code">nested</code> 指令执行自定义指令开始和结束标签中间的模板片段。
			嵌套的片段可以包含模板中任意合法的内容：插值，指令等...它在上下文环境中被执行，
			也就是宏被调用的地方，而不是宏定义体的上下文中。因此，比如，
			你不能看到嵌套部分的宏的局部变量。如果你没有调用 <code class="inline-code">nested</code> 指令，
			自定义指令开始和结束标记中的部分将会被忽略。</p>

            <p>比如：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro do_twice&gt;
  1. &lt;#nested&gt;
  2. &lt;#nested&gt;
&lt;/#macro&gt;
&lt;@do_twice&gt;something&lt;/@do_twice&gt;</pre></div>

            <p>将会输出：</p>

            

<div class="code-wrapper"><pre class="code-block code-output">  1. something
  2. something
 </pre></div>

            <p>nested 指令可以对嵌套内容创建循环变量。例如：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro do_thrice&gt;
  &lt;#nested <strong>1</strong>&gt;
  &lt;#nested <strong>2</strong>&gt;
  &lt;#nested <strong>3</strong>&gt;
&lt;/#macro&gt;
&lt;@do_thrice <strong>; x</strong>&gt;
  ${<strong>x</strong>} Anything.
&lt;/@do_thrice&gt;</pre></div>

            <p>将会输出：</p>

            

<div class="code-wrapper"><pre class="code-block code-output">  1 Anything.
  2 Anything.
  3 Anything.
 </pre></div>

            <p>更为复杂的示例：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro repeat count&gt;
  &lt;#list 1..count as x&gt;
    &lt;#nested <strong>x, x/2, x==count</strong>&gt;
  &lt;/#list&gt;
&lt;/#macro&gt;
&lt;@repeat count=4 ; <strong>c, halfc, last</strong>&gt;
  ${<strong>c</strong>}. ${<strong>halfc</strong>}&lt;#if <strong>last</strong>&gt; Last!&lt;/#if&gt;
&lt;/@repeat&gt;</pre></div>

            <p>将会输出：</p>

            

<div class="code-wrapper"><pre class="code-block code-output">  1. 0.5
  2. 1
  3. 1.5
  4. 2 Last!
 </pre></div>
          

          
            



<h3 class="content-header header-section3" id="autoid_106">return</h3>


            <a name="ref.directive.macro.return"></a>

            <p>使用 <code class="inline-code">return</code> 指令，
			你可以在任意位置留下一个宏或函数定义。比如：</p>

            

<div class="code-wrapper"><pre class="code-block code-template">&lt;#macro test&gt;
  Test text
  &lt;#return&gt;
  Will not be printed.
&lt;/#macro&gt;
&lt;@test/&gt;</pre></div>

            <p>将会输出：</p>

            

<div class="code-wrapper"><pre class="code-block code-output">  Test text
  </pre></div>
          
        <div class="bottom-pagers-wrapper"><div class="pagers bottom"><a class="paging-arrow previous" href="ref_directive_local.html"><span>Previous</span></a><a class="paging-arrow next" href="ref_directive_noparse.html"><span>Next</span></a></div></div></div></div>      </div>
    </div>
<div class="site-footer"><div class="site-width"><div class="footer-top"><div class="col-left sitemap"><div class="column"><h3 class="column-header">Overview</h3><ul><li><a href="http://freemarker.org/index.html">What is FreeMarker?</a></li><li><a href="http://freemarker.org/freemarkerdownload.html">Download</a></li><li><a href="app_versions.html">Version history</a></li><li><a href="http://freemarker.org/history.html">About us</a></li><li><a itemprop="license" href="app_license.html">License</a></li></ul></div><div class="column"><h3 class="column-header">Handy stuff</h3><ul><li><a href="http://freemarker-online.kenshoo.com/">Try template online</a></li><li><a href="dgui_template_exp.html#exp_cheatsheet">Expressions cheatsheet</a></li><li><a href="ref_directive_alphaidx.html">#directives</a></li><li><a href="ref_builtins_alphaidx.html">?built_ins</a></li><li><a href="ref_specvar.html">.special_vars</a></li></ul></div><div class="column"><h3 class="column-header">Community</h3><ul><li><a href="https://github.com/nanlei/freemarker/tree/manual-zh-2.3-gae/src/manual">Chinese Manual on Github</a></li><li><a href="https://github.com/freemarker/freemarker">FreeMarker on Github</a></li><li><a href="https://twitter.com/freemarker">Follow us on Twitter</a></li><li><a href="https://sourceforge.net/p/freemarker/bugs/new/">Report a bug</a></li><li><a href="http://stackoverflow.com/questions/ask?tags=freemarker">Ask a question</a></li><li><a href="http://freemarker.org/mailing-lists.html">Mailing lists</a></li></ul></div></div><div class="col-right"><ul class="social-icons"><li><a class="github" href="https://github.com/freemarker/freemarker">Github</a></li><li><a class="twitter" href="https://twitter.com/freemarker">Twitter</a></li><li><a class="stack-overflow" href="http://stackoverflow.com/questions/ask?tags=freemarker">Stack Overflow</a></li></ul><a class="xxe" href="http://www.xmlmind.com/xmleditor/" rel="nofollow" title="Edited with XMLMind XML Editor"><span>Edited with XMLMind XML Editor</span></a></div></div><div class="footer-bottom"><p><span class="generated-for-product">Generated for: Freemarker 2.3.23</span><span class="last-updated"> Last generated:
<time itemprop="dateModified" datetime="2015-09-18T14:38:51Z" title="Friday, September 18, 2015 2:38:51 PM GMT">2015-09-18 14:38:51 GMT</time></span></p> <p class="copyright">
© <span itemprop="copyrightYear">1999</span>–2015
<a itemtype="http://schema.org/Organization" itemprop="copyrightHolder" href="http://freemarker.org">The FreeMarker Project</a>. All rights reserved. </p>
</div></div></div></body>
</html>
